<HTML>
<HEAD>
<TITLE>View Object Documentation</TITLE>
</HEAD>
<BODY>
<A HREF="#toc">Table of Contents</A><P>
_________________________________________________________________
<P>

<H2><A NAME="sect1" HREF="#toc1"><B>NAME</B></A></H2>
v_open - create and manipulate a view object.
<P>

<H2><A NAME="sect2" HREF="#toc2"><B>SYNOPSIS</B></A></H2>
<B>v_open</B> [<I>viewName</I>]
<P>

<H2><A NAME="sect8" HREF="#toc8"><B>DESCRIPTION</B></A></H2>
The <B>v_open</B> command creates a new view object
(given by the <I>viewName</I> argument).
The <B>v_open</B> command returns its <I>viewName</I> argument.
At the time this command is invoked, there must not exist a
view object named <I>viewName</I>.
<P>

<H2><A NAME="sect9" HREF="#toc9"><B>METHODS</B></A></H2>
The <B>v_open</B> command creates a new Tcl command whose name
is <I>viewName</I>. This command may be used to invoke various
operations on the view object. It has the following general
form:
<P>
<I>viewName</I> <I>option</I> ?<I>arg</I> <I>arg</I> ...?
<P>
<I>Option</I> and the <I>arg</I>s determine the exact behavior of the command.
The following commands are possible for view objects:
<P>
<DL>
<DT><I>viewName</I> <A NAME= "aet"><B>aet</B></A> <I>azimuth elevation</I> [<I>twist</I>]</DT>
<DD> Set the view orientation by rotating the eye position about the
center of the viewing cube.
The eye position is determined by the supplied azimuth and elevation angles (degrees).
The <I>azimuth</I> angle is measured in the XY plane with the positive X direction
corresponding to an azimuth of zero degrees.
Positive azimuth angles are measured counter&#173clockwise about the positive Z axis.
Elevation angles are measured from the XY plane with +90 degrees corresponding to
the positive Z direction and -90  corresponding to the negative Z direction.
If an optional <I>twist</I> angle is included, the view will be rotated about
the viewing direction by the specified <I>twist</I> angle.
If no arguments are provided, the current view orientation is returned.
</DD>
<P>
<DT><I>viewName</I> <A NAME="base2local"><B>base2local</B></A></DT>
<DD>Return the base units (i.e. mm) to local units conversion factor.</DD>
<P>
<DT><I>viewName</I> <A NAME= "center"><B>center</B></A> [<I>x y z</I>]</DT>
<DD> Position the center of the viewing cube at the specified model coordinates.
This is accomplished by moving the eye position while not changing the viewing direction.
The coordinates are expected in millimeters.
If no arguments are provided, the current center coordinates are returned.
</DD>
<P>
<DT><I>viewName</I> <A NAME="close"><B>close</B></A></DT>
<DD>Close/destroy the view object</DD>
<P>
<DT><I>viewName</I> <A NAME="eye"><B>eye</B></A> <I>x y z</I></DT>
<DD>Position the eye point at <I>x, y</I>, and <I>z</I> (specified
in mm). </DD>
<P>
<DT><I>viewName</I> <A NAME="eye_pos"><B>eye_pos</B></A></DT>
<DD></DD>
<P>
<DT><I>viewName</I> <A NAME="invSize"><B>invSize</B></A></DT>
<DD>Return the inverse view size.</DD>
<P>
<DT><I>viewName</I> <A NAME="local2base"><B>local2base</B></A></DT>
<DD>Return the local units to base units (i.e. mm) conversion factor.</DD>
<P>
<DT><I>viewName</I> <A NAME="lookat"><B>lookat</B></A></DT>
<DD>Adjust the current view such that the eye
is looking in the direction of the given coordinates, but does not move the eye
point nor change the viewsize. This is similar to just rotating the viewers head
to look at the specified point, putting that point in the center of the <I>mged</I>
display.
</DD>
<P>
<DT><I>viewName</I> <A NAME= "model2view"><B>model2view</B></A></DT>
<DD> Return a matrix that can be used to transform model coordinates
to view coordinates.
</DD>
<P>
<DT><I>viewName</I> <A NAME= "observer"><B>observer</B></A> [<I>subcommand</I>]</DT>
<DD>This command is used to maintain a list of observers. Observers
are objects who have registered an interest in this view object and
are notified when the view changes.
<P>
	<DL>
	<DT><I>viewName observer</I> <B>attach</B> <I>obs</I> [<I>command</I>]</DT>
	<DD>Add the specified observer, <I>obs</I>, to the list of observers.
	If <I>command</I> is specified then it is executed each time the view
	changes. Otherwise, the observer is expected to have an update method
	which is called with the name of this view object as an argument.
	</DD>
<P>
	<DT><I>viewName observer</I> <B>detach</B> <I>obs</I></DT>
	<DD>Remove the specified observer, <I>obs</I>, from the list of observers.
	</DD>
<P>
	<DT><I>viewName observer</I> <B>show</B></DT>
	<DD>Return the list of observers for this view object.
	</DD>
	</DL>
</DD>
<P>
<DT><I>viewName</I> <A NAME="orientation"><B>orientation</B></A></DT>
<DD>Set the view direction
from the <a href="brlcad_glossary.html#QUATERNION">quaternion</a> specified
on the command line.
</DD>
<P>
<DT><I>viewName</I> <A NAME= "perspective"><B>perspective</B></A> [<I>angle</I>]</DT>
<DD>Set/get the perspective angle.
</DD>
<P>
<DT><I>viewName</I> <A NAME="pmat"><B>pmat</B></A></DT>
<DD>Return the perspective matrix.</DD>
<P>
<DT><I>viewName</I> <A NAME= "pmodel2view"><B>pmodel2view</B></A></DT>
<DD> Return a matrix that can be used to transform model coordinates
to view coordinates with perspective.
</DD>
<P>
<DT><I>viewName</I> <A NAME="rmat"><B>rmat</B></A> [<I>matrix</I>]</DT>
<DD>Set/get the rotation matrix.</DD>
<P>
<DT><I>viewName</I> <A NAME= "rot"><B>rot</B></A> <I>x y z</I></DT>
<DD>Rotate the view by <I>x, y, z</I> degrees.
</DD>
<P>
<DT><I>viewName</I> <A NAME= "size"><B>size</B></A> [<I>s</I>]</DT>
<DD> Set/get the size of the viewing cube.
</DD>
<P>
<DT><I>viewName</I> <A NAME= "slew"><B>slew</B></A> <I>x y</I></DT>
<DD>Move the view center to (<I>x</I>, <I>y</I>).
The parameters <I>x, y</I> are integer values relative to the screen.
For example, the center of the screen is (0, 0), the upper left corner is
(-1, 1) and the lower right is (1, -1).
</DD>
<P>
<DT><I>viewName</I> <A NAME= "tra"><B>tra</B></A> <I>x y z</I></DT>
<DD>Move the view center by the distances indicated
by <I>x, y, and z</I> (local units).
</DD>
<P>
<DT><I>viewName</I> <A NAME="units"><B>units</B></A></DT>
<DD>Set/get the local units.</DD>
<P>
<DT><I>viewName</I> <A NAME="view2model"><B>view2model</B></A></DT>
<DD>Return a matrix that can be used to transform view coordinates
to model coordinates.</DD>
<P>
<DT><I>viewName</I> <A NAME= "zoom"><B>zoom</B></A> <I>sf</I></DT>
<DD> Change the size of the viewing cube by a factor of <I>sf</I>.
</DD>
<P>
</DL>

<H2><A NAME="sect16" HREF="#toc16"><B>EXAMPLE</B></A></H2>
The following sequence creates a view object and
changes its parameters.
<P>
cwish> v_open v
<BR>
v
<BR>
cwish> v aet &quot;35 25 0&quot;
<BR>
cwish> v size 500
<BR>
cwish> v center "100 0 0"
<P>

<H2><A NAME="sect17" HREF="#toc17"><B>ACKNOWLEDGMENTS:</B></A></H2>

Mark L. Ulferts &lt;mulferts@austin.dsccc.com&gt;
<PRE>        Basic layout for documenting classes.</PRE>
<P>

<H2><A NAME="sect18" HREF="#toc18"><B>AUTHOR</B></A></H2>
<P>
Robert G. Parker
<P>

<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc1" HREF="#sect1">NAME</A></LI>
<LI><A NAME="toc2" HREF="#sect2">SYNOPSIS</A></LI>
<LI><A NAME="toc8" HREF="#sect8">DESCRIPTION</A></LI>
<LI><A NAME="toc9" HREF="#sect9">METHODS</A></LI>
<LI><A NAME="toc16" HREF="#sect16">EXAMPLE</A></LI>
<LI><A NAME="toc17" HREF="#sect17">ACKNOWLEDGMENTS</A></LI>
<LI><A NAME="toc18" HREF="#sect18">AUTHOR</A></LI>
</UL>
</BODY>
</HTML>
